feat(analytics): World ID unique-verifications data layer (1/3) - #2191

Dual v3/v4 action-day rollup tables with cascading FKs, the singleton
watermark state table, the tracked return-shape table, the atomic
five-minute dual-source rollup function under advisory lock (533214,43),
the combined app-daily read function, service-only Hasura metadata, the
protected cron route with a rollout-disable gate, operator scripts for
the out-of-band v3 index and backfill validation, and the fresh-stack
contract harness with its data-layer tests.

The default and --million paths invoked integration.test.ts and
million.test.ts, which land with the read slice; jest exits 1 on a
pattern with no matches, so both entrypoints failed on this branch.
The read slice restores them alongside the files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A plain CREATE INDEX in the transactional migration blocks nullifier_v4
verification inserts for the build duration while old pods serve during
a rolling deploy. Build it out of band with CONCURRENTLY like the v3
twin: the operator script now creates and validity-gates both indexes,
and the backfill gate refuses to run until both are valid.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ats_daily

The API contract (legacy_actions) and UI scope type (source: "legacy")
already named this concept 'legacy'; only the SQL layer said 'v3'. v3
was never a real protocol generation here - nullifier/action predate
v4 entirely and internally split by engine (on-chain/cloud), not by
any versioning scheme. Align the table/index name and source tags with
the terminology the other two layers already settled on.

Regenerated graphql.schema.json/graphql.ts against the renamed table;
tsc and prettier clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The team's concern with the one-shot design: a full-history backfill
runs as one unbounded transaction, so a failure loses all progress and
nothing reports where it died.

rollup_world_id_analytics() now takes max_advance_days, capping how far
one call may advance the watermark in whole UTC days (NULL = unbounded).
The rebuild start stays derived from the watermark, so no sequence of
calls can skip a range. A capped bootstrap from -infinity anchors at the
oldest raw row (-infinity + interval is still -infinity), deletes are
bounded to the chunk's date range, and once the watermark is inside the
25-hour overlap horizon - where the day-aligned target can land at or
below the watermark and would otherwise never advance - the call
finishes at the cutoff instead of stalling.

backfill_world_id_analytics(chunk_days DEFAULT 1) is a new operator-only
procedure that loops the rollup and commits between chunks: an
interrupted backfill keeps its progress, a rerun resumes from the
committed watermark, and the watermark doubles as a live progress
indicator. It aborts loudly on a lock miss and aborts rather than spins
if a chunk ever fails to advance the watermark. The deployment gate's
phase 1 calls it and no longer auto-resets the watermark; only a parity
validation failure requires the documented explicit reset.

The cron route passes max_advance_days: 30 - invisible in steady state
(~25h window), bounds catch-up after an outage to 30 days per tick - and
reports distinct outcomes (advanced with processed_through, lock_missed
as a warning, disabled), so a stalled watermark is observable and lock
misses are no longer silent successes.

Migration 1785459169000 edited in place (unreleased); local stacks that
already applied it must be recreated. Fresh-stack data-slice suite
17/17 including a new chunked-rollup suite (cap math, bootstrap anchor,
empty-database termination, chunk-boundary counts, committed chunks
surviving a failed chunk and resuming); route unit tests 6/6; tsc and
prettier clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A capped rebuild anchors at the oldest raw row, so a rolled row whose
raw rows were later deleted survives a watermark-only reset and fails
parity validation on every retry (reproduced: the gate loops forever).
The documented reset now truncates both rollup tables before resetting
the watermark, and a new gate case pins the trapped scenario and its
recovery. Codex review finding on #2191.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…uild

One SQL function rebuilds an explicit UTC date window (delete + recount,
idempotent); no dates means the trailing ~25h. The watermark singleton,
its bootstrap/clamp logic, and the backfill procedure are gone. The route
gains a dated mode (chunked loop, failed_ranges response, fresh service
client per chunk) that bypasses the rollout flag for operator backfill
and repair; the cron mode stays fail-closed behind it. Advisory lock is
now a blocking wait: Hasura hides Postgres SQLSTATEs from non-admin
roles, so a try-lock miss was indistinguishable from failure. Cron slows
to */15 with matching tolerance. The ops script no longer backfills; it
is the index gates plus a self-contained parity check (catch-up inside
one repeatable-read snapshot, complete days only) whose mismatch sample
names the exact ranges to re-POST — no reset step exists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Soam's ruling: hasura/operations/world-id-analytics contains exactly one
file — the concurrent index build — because one file is what the platform
team runs. backfill-and-validate.sql is deleted; the parity comparison it
carried now lives in the test suite (readParityMismatches in
canonical-analytics.ts, exercised by rollup-parity.test.ts and the e2e
runbook suite), where it already proved coverage, corruption, and
orphan-sweep behavior. Operator flow is now: index script, dated backfill
POSTs until failed_ranges is empty, flag on.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A concurrent action deletion locks the parent row first and then cascades
into the stats rows the running window just deleted; the rollup's recount
insert then waits on that parent — a lock cycle whose victim is nearly
always the user's delete, because the deletion is structurally the earlier
waiter and PostgreSQL's detector aborts the process that has waited
deadlock_timeout. Reproduced 3/3 on postgres:14 (delete 40P01, rollup
committed); the existing race test missed it because a first-ever rollup
deletes no child rows. Ordered FOR KEY SHARE pre-locks on the recount's
parent actions restore parent-before-child ordering on both sides: the
deletion now parks briefly on the parent and cascades cleanly after the
window commits — verified 3/3, plus a regression test against a re-rolled
window.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>